---
title: Convert a number to English words
summary: Spells out a Long numeric value as English words via recursive magnitude decomposition.
status: draft
owner: SAIF Documentation Generation
last_reviewed: 2026-08-21
library: SAIF.Business.Utilities
reference_type: embedded
operation_id: OP-UTIL-002
trigger: Call to mdlTextConversion.NumberToText
---

# Convert a number to English words

This operation converts a `Long` numeric value into its English-word representation (e.g., for check or amount-in-words rendering), using recursive magnitude decomposition down to the ones/teens level.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-UTIL-002 |
| **Trigger** | Caller invokes `mdlTextConversion.NumberToText(n)`. |
| **Inputs** | A `Long` value `n`. |
| **Outputs** | A `String` spelling out `n` in English words. |
| **Primary components** | `mdlTextConversion.NumberToText`, `mdlTextConversion.RoundDown` |
| **Entry point** | `SAIF.Business.Utilities\mdlTextConversion.vb` |

## Steps

1. Reject values greater than 999,999,999,999,999 by throwing `ApplicationException("Number too large to convert to text...")`. ([BR-UTIL-010](../business-rules.md#br-util-010-numbertotext-upper-bound-is-enforced))
   - On failure: exception propagates to the caller; no partial result is returned.
2. If the value is negative, prefix "Minus " and recurse on the absolute value.
3. If the value is zero, return an empty string (no "Zero" word emitted). ([BR-UTIL-011](../business-rules.md#br-util-011-zero-renders-as-an-empty-string%2C-not-the-word-%22zero%22))
4. If the value is 1–19, look up the word directly from a fixed ones/teens array.
5. If the value is 20–99, look up the tens word (Twenty…Ninety) and recurse on the remainder (`n Mod 10`) for the ones digit.
6. If the value is 100–199, prefix "One Hundred " and recurse on the remainder (`n Mod 100`).
7. If the value is 200–999, recurse to spell the hundreds digit, append "Hundred ", and recurse on the remainder (`n Mod 100`).
8. Apply the same "≤1999-of-that-unit special case, else group-of-3 recursion" pattern successively for Thousand, Million, Billion, and Trillion magnitudes: each level has a branch that says "One {Unit} " for values ≤ 1,999 of that unit, and a general branch that recurses to spell the leading digit group, appends "{Unit} ", then recurses on the remainder.
   - Private helper `RoundDown(inValue, inDivisor)` performs integer floor-division used by the recursion at each magnitude level.
9. Return the fully composed English-word string.

No step in this operation delegates into another project/library in this repository or into a SAIF BOF Framework operation — the operation is entirely self-contained BCL-only integer arithmetic.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Trigger: NumberToText call]) --> Bound{n greater than 999,999,999,999,999?}
	Bound -->|Yes| Throw([Throw ApplicationException])
	Bound -->|No| Sign{n negative?}
	Sign -->|Yes| Minus[Prefix Minus, recurse on abs value]
	Sign -->|No| Zero{n = 0?}
	Zero -->|Yes| EmptyStr([Return empty string])
	Zero -->|No| Magnitude[Recurse by magnitude:<br>ones/teens, tens, hundreds,<br>thousands, millions, billions, trillions]
	Magnitude --> End([Return spelled-out words])
```

## Failure and edge-case behavior
- `n` greater than 999,999,999,999,999: throws `ApplicationException`, no result returned.
- `n` equal to 0: returns an empty string rather than the word "Zero", so whole-hundred/thousand values omit trailing "Zero" text.
- `n` negative: recurses on the absolute value with a "Minus " prefix.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- SAIF.Business.Utilities\mdlTextConversion.vb
- .saifdocgen/state/runs/20260821-113120-claims-bof-web-legal/analysis/TSK007-analysis.md